---
title: "Worker-Watcher und Agent-Solutions-Zentrale – Projektstand"
date: 2026-08-02
updated: 2026-08-02
status: produktiv-mit-offenen-ui-punkten
type: projektabschluss
project:
  - worker-watcher
  - agent-solutions-zentrale
systems:
  - VPS IONOS
  - Worker-Watcher
  - Agent Solutions Zentrale Steuerung
tags:
  - worker-watcher
  - agent-solutions
  - monitoring
  - hermes
  - vps
  - codex
  - projektstand
---

# Worker-Watcher und Agent-Solutions-Zentrale – Projektstand

## Kurzstatus

> [!status] Projektstatus
> - Worker-Watcher: produktiv aktiv; `hermes-worker-watcher.service` läuft seit `2026-08-02T17:01:40Z`.
> - Worker-Watcher-Code: lokal verifiziert mit Compileall, Ruff, Mypy und 34 Pytest-Tests.
> - Warnkachel: produktiv aktiv über die serverseitige Portal-Brücke.
> - Gesamtzustand des Watchers: `degraded` bei `database_status=ok`.
> - Warnzusammenfassung der Kachel: `critical`, mit 3 aktiven Warnfällen.
> - Ursache des `degraded`-Zustands: überwachte Anwendungen und ein fehlender Docker-Container, nicht ein ausgefallener Watcher.
> - Header der Worker-Oberfläche: nach der letzten Live-Abnahme innerhalb des gemeinsamen Inhaltsrahmens; die frühere Korrektur ist nachgewiesen.
> - Verbleibender UI-Punkt: sichtbare Resttexte wie `?ffnen` im Portal sind nicht Bestandteil dieser Dokumentations- oder Watcher-Arbeiten und wurden nicht korrigiert.

Die aktuelle technische Momentaufnahme wurde am `2026-08-02T17:09:49Z` über die lokalen API-Endpunkte und die SQLite-Datenbank im Read-only-Modus erhoben. Die laufende Anwendung ist technisch erreichbar; fachlich bleiben überwachte Probleme aktiv.

## Ausgangslage

Der Bedarf war eine zentrale, möglichst breit einsetzbare Überwachung von KI-Workern und Automationen. Der Ausführungsort eines Workers ist nicht zuverlässig auf den VPS begrenzbar. Deshalb überwacht der Worker-Watcher lokale Systemd-Dienste, Docker-Container und Prozesse und besitzt zusätzlich eine Remote-Agent-Schnittstelle für spätere oder außerhalb des VPS laufende Quellen.

Der Watcher soll Zustände sichtbar machen, ohne produktive Jobs zu steuern. Er ist keine Start-/Stop-Zentrale, kein Auto-Healing-System und keine zweite fachliche Alarmierungslogik. Seine Aufgabe ist die normalisierte Beobachtung, Speicherung, Historisierung und Bereitstellung von Statusdaten.

Die Agent-Solutions-Zentrale war zunächst eine statische Navigationsseite. Sie erhielt eine Warnkachel, damit der Nutzer den verdichteten Zustand der überwachten Worker direkt am Einstiegspunkt erkennt und zur vollständigen Worker-Überwachung wechseln kann.

## Zielarchitektur

Die umgesetzte Kette lautet:

```text
Lokaler Collector oder Remote-Agent
        ↓
Normalisierung der Beobachtung
        ↓
SQLite: aktueller Status, Beobachtungen, Ereignisse, Collector-Läufe
        ↓
HTTP-API und Worker-Watcher-Weboberfläche
        ↓
Serverseitige Portal-Brücke zur Agent-Solutions-Zentrale
        ↓
Verdichtete Warnkachel und Verlinkung zur Detailansicht
```

Die Collector überwachen ihre Quellen read-only. Die Datenbank des Watchers wird für die eigene Beobachtungs- und Ereignishistorie beschrieben. Ein Remote-Agent darf Beobachtungen an die API senden; dadurch wird der Watcher-Datenbestand erweitert, aber kein überwachtes Produktivsystem gesteuert.

Wichtige Trennungen:

- Quelle beziehungsweise Anwendung: gemeldeter Zustand des Dienstes, Containers oder Prozesses.
- Watcher: Fähigkeit, Quellen zu lesen, zu normalisieren und zu speichern.
- Portal: reine Darstellung einer vom Watcher gelieferten Zusammenfassung.
- Warnkachel: keine eigene zweite Bewertung der einzelnen Jobs.

## Beteiligte Systeme

| System | Rolle | Aktueller Nachweis |
|---|---|---|
| Worker-Watcher | Zentrale Bewertungs-, Speicher- und API-Schicht | `hermes-worker-watcher.service` aktiv; `/health/live` liefert `{"status":"live"}` |
| SQLite-Datenbank | Aktueller Status, Beobachtungen, Ereignis- und Collector-Historie | `/opt/struktur/hermes-workspace/worker-watcher/data/watcher.sqlite`, Schema-Version 2 |
| Agent Solutions Zentrale | Portal mit Navigationskacheln und Warnkachel | `portal.service` aktiv; `/api/worker-alerts` liefert `ok=true` |
| Systemd | Quelle für 15 konfigurierte Dienstdefinitionen | `systemd`-Collector aktiv |
| Docker | Quelle für 6 konfigurierte Containerdefinitionen | `docker`-Collector aktiv; `telefon-agent` fehlt |
| `/proc` | Quelle für den Prozess `hermes` | `process`-Collector aktiv |
| Remote-Agent-Schnittstelle | Erweiterung für Worker außerhalb des lokalen Collector-Scope | aktiviert, aktuell 0 registrierte Agenten |

## Relevante URLs

Öffentliche beziehungsweise in der Oberfläche hinterlegte Ziele:

- Worker-Watcher: `https://worker.agentsolutions-mallorca.com`
- Agent Solutions Zentrale: `https://agentsolutions-mallorca.com`
- Portal-Link zur Worker-Überwachung: `https://worker.agentsolutions-mallorca.com`

Lokale Prüfziele:

- Worker-Watcher: `http://127.0.0.1:8088/`
- Portal: `http://127.0.0.1:5052/`
- Portal-Watcher-Brücke: `http://127.0.0.1:5052/api/worker-alerts`

Die öffentlichen URLs wurden als UI-Ziele beziehungsweise Konfiguration dokumentiert. Die in diesem Dokument maßgeblichen HTTP-Abnahmen erfolgten gegen die lokalen Dienste.

## Relevante Dienste und Projektpfade

### Worker-Watcher

- Projekt: `/opt/struktur/hermes-workspace/worker-watcher`
- Startbefehl:

```text
/opt/struktur/hermes-workspace/worker-watcher/.venv/bin/watcher --config /opt/struktur/hermes-workspace/worker-watcher/config.yaml serve
```

- Systemd-Unit: `hermes-worker-watcher.service`
- Arbeitsverzeichnis: `/opt/struktur/hermes-workspace/worker-watcher`
- Python-Version: `3.12.3` laut Audit vom 01.08.2026
- API-Host und Port: `127.0.0.1:8088`
- Zyklusintervall: 60 Sekunden
- Anzeigezeitzone: `Europe/Madrid`
- Datenbank: `/opt/struktur/hermes-workspace/worker-watcher/data/watcher.sqlite`

### Agent Solutions Zentrale

- Projekt: `/opt/struktur/portal`
- Produktive Quelldatei: `/opt/struktur/portal/app.py`
- Systemd-Unit: `portal.service`
- Startbefehl:

```text
/usr/bin/python3 /opt/struktur/portal/app.py
```

- Arbeitsverzeichnis: `/opt/struktur/portal`
- Lokaler Port: `127.0.0.1:5052`
- Watcher-Brücke: standardmäßig `http://127.0.0.1:8088/api/v1/alerts/summary`

## Umgesetzte Funktionen des Worker-Watchers

- Lokale Collector für Systemd, Docker und Prozesse.
- Konfigurierbare, derzeit deaktivierte Collector für Cron und Generic Worker.
- Isolierte Collector-Ausführung mit individuellem Timeout.
- Normalisierung in getrennte Statusachsen.
- SQLite-Migrationen und versioniertes Schema.
- Aktueller Status je Job-Instanz.
- Beobachtungs- und Statusereignishistorie.
- Collector-Laufhistorie und Watcher-Ereignisse.
- Read-only Health-, Status-, Job-, Ereignis- und Collector-Endpunkte.
- Remote-Agent-Registrierung und idempotenter Remote-Event-Eingang.
- Verdichteter Endpunkt `/api/v1/alerts/summary` für die Portalwarnkachel.
- Deutsche Weboberfläche mit getrennten Gruppen für zentrale Infrastruktur, Projekt-Worker, Automationen, weitere Aufgaben und Remote-Agenten.
- Manueller und automatischer Browserabruf der Weboberfläche.

Nicht umgesetzt und bewusst nicht Teil der Architektur:

- Auto-Healing.
- Starten, Stoppen oder Neustarten überwacht­er Jobs aus dem Watcher.
- Künstlich angelegte Remote-Agenten.
- Browser-Spezialcollector ohne nachgewiesenen Browser-Worker.

## Datenmodell und Statuslogik

Das SQLite-Schema enthält unter anderem:

| Entität | Tabelle | Zweck |
|---|---|---|
| Job | `jobs` | Logische Workerdefinition |
| Instanz | `job_instances` | Konkrete Ausprägung nach Host, Runtime und Quelle |
| Run | `job_runs` | Echte Läufe mit Run-ID, Laufzeit, Exitcode und Fehler |
| Beobachtung | `job_observations` | Einzelne Collector- oder Remote-Beobachtung |
| Aktueller Status | `job_status_current` | Letzter normalisierter Status je Instanz |
| Statusereignis | `status_events` | Relevante Änderungen des effektiven Status |
| Collector-Lauf | `collector_runs` | Erfolg, Fehler, Laufzeit und Beobachtungszahlen |
| Watcher-Ereignis | `watcher_events` | Collector- und Watcherfehler |
| Remote-Agent | `execution_agents` | Agentenidentität, Umgebung, Host und Heartbeat |
| Remote-Event | `remote_events` | Idempotenter Eingang externer Beobachtungen |

Die Statusdimensionen sind getrennt:

- `operational_state`: `scheduled`, `running`, `waiting`, `paused`, `stopped`, `completed`, `unknown`.
- `health_status`: `healthy`, `degraded`, `failed`, `stale`, `unknown`.
- `observation_status`: `fresh`, `stale`, `unavailable`.
- `severity`: `info`, `warning`, `critical`.

Beispiele der Normalisierung:

- Nicht lesbare Quelle oder Berechtigungsproblem → `health_status=unknown`, `observation_status=unavailable`.
- Nichtnull-Exitcode → `operational_state=stopped`, `health_status=failed`.
- Pausierter Job → `operational_state=paused`, nicht automatisch `failed` oder `stale`.
- Bei `unavailable` bleibt der letzte bekannte Health- und Operational-Status erhalten; die aktuelle Beobachtung wird separat als nicht verfügbar markiert.

Der globale Watcherstatus ist aktuell `healthy` oder `degraded`. Im aktuellen Live-Stand ist die Datenbank `ok`, aber es gibt einen Collectorfehler sowie Jobprobleme. Daher lautet der Watcherstatus `degraded`.

## API-Endpunkte

Die folgenden Endpunkte sind im aktuellen HTTP-Server vorhanden. GET-Endpunkte lesen Watcher-Daten; sie steuern keine überwachten Systeme. Die beiden POST-Endpunkte betreffen ausschließlich den Eingang von Remote-Agent-Daten und verlangen bei gesetztem Agent-Token die konfigurierte Authentifizierung.

| Endpunkt | Zweck | Nutzer / Bedeutung |
|---|---|---|
| `GET /health` | Vollständige technische Watcher-Gesundheit mit Datenbank-, Collector-, Job- und Zyklusdaten | Betrieb, Dashboard und Abnahme |
| `GET /health/live` | Minimaler Prozess-Liveness-Nachweis | Systemd-/Load-Balancer-Prüfung |
| `GET /health/ready` | Readiness inklusive Schema-Version | Start- und Betriebsprüfung |
| `GET /api/v1/status` | Aktueller Watcherstatus, Collectorstatus und Jobzähler | Worker-Oberfläche und externe Read-only-Prüfung |
| `GET /api/v1/jobs` | Liste der aktuellen Job- und Instanzdaten | Tabellen der Worker-Oberfläche |
| `GET /api/v1/jobs/{instance_id}` | Detaildaten einer einzelnen Job-Instanz | Detailprüfung eines konkreten Workers |
| `GET /api/v1/workers` | Worker-orientierte Sicht auf registrierte Beobachtungen | API- und Integrationsnutzer |
| `GET /api/v1/agents` | Registrierte Remote-Agenten | Agentenbereich der Oberfläche |
| `GET /api/v1/remote-events` | Eingegangene Remote-Events | Diagnose und Idempotenzprüfung |
| `GET /api/v1/events` | Status- und Watcher-Ereignisse | Ereignishistorie der Oberfläche |
| `GET /api/v1/collectors` | Konfiguration, Aktivierung und Version der Collector | Collector-Transparenz |
| `GET /api/v1/collectors/runs` | Historie der Collector-Läufe | Lauf- und Fehlerdiagnose |
| `GET /api/v1/collectors/{collector_name}` | Detailinformationen eines Collectors | Technische Einzelprüfung |
| `GET /api/v1/alerts/summary` | Verdichtete Warnzusammenfassung für die Portal-Kachel | Agent-Solutions-Zentrale; keine zweite Einzeljobbewertung |
| `POST /api/v1/agents/register` | Registrierung eines Remote-Agenten | Nur Remote-Agent-Integration; schreibt Watcher-Metadaten |
| `POST /api/v1/agents/events` | Idempotenter Eingang eines Remote-Events | Nur Remote-Agent-Integration; erzeugt Beobachtungsdaten |

Zum Dokumentationszeitpunkt antworteten die für die Abnahme verwendeten GET-Endpunkte lokal mit HTTP 200. Die Oberfläche nutzt insbesondere `/api/v1/status`, `/api/v1/jobs`, `/api/v1/agents` und `/api/v1/events`; die Portal-Brücke nutzt `/api/v1/alerts/summary`.

## Collector und überwachte Quellen

Aktuelle Konfiguration aus `/opt/struktur/hermes-workspace/worker-watcher/config.yaml`:

| Collector | Typ | Aktiv | Definitionen |
|---|---|---:|---:|
| `systemd` | `systemd` | ja | 15 Dienste |
| `docker` | `docker` | ja | 6 Container |
| `process` | `process` | ja | Prozess `hermes` |
| `cron` | `cron` | nein | 0 |
| `generic-worker` | `generic_worker` | nein | 0 |

Der aktuelle Live-Datenbankstand vom `2026-08-02T17:08:45Z`:

- Jobs: `22`
- Job-Instanzen: `22`
- Beobachtungen: `36.429`
- Aktueller Statuszeilen: `22`
- Statusereignisse: `22`
- Collector-Läufe: `4.993`
- Watcher-Ereignisse: `1.640`
- Echte Runs in `job_runs`: `0`
- Remote-Agenten: `0`
- Remote-Events: `0`
- Runtime-Typen: `docker`, `process`, `systemd`

Die Auditwerte vom `2026-08-01` waren `4.991` Beobachtungen, `706` Collector-Läufe und `211` Watcher-Ereignisse. Die höheren aktuellen Werte sind durch weitere laufende Prüfzyklen entstanden und ersetzen die historischen Werte nicht.

Ein Browser-Scope wurde im Audit read-only geprüft. Es wurden keine Chrome-, Chromium-, Playwright-, Puppeteer- oder Selenium-Prozesse gefunden; ein File-Browser ist vorhanden. Ein Browser-Spezialcollector ist deshalb nicht begründet.

## Tabellen- und Sortierfunktionen

Die Worker-Oberfläche enthält fachlich getrennte Tabellen für zentrale Infrastruktur, Projekt-Worker, Automationen und Hintergrund-Worker, weitere überwachte Aufgaben, Remote-Agenten sowie letzte Ereignisse.

Umgesetzt beziehungsweise im Code nachgewiesen:

- Spalten `Letzte Aktivität`, `Seit`, `Betriebszustand`, `Gesundheit`, `Beobachtung`, `Nächster Lauf / Überfällig` und `Grund`.
- Separate Sortierzustände je Tabelle beziehungsweise Fachgruppe.
- Aufsteigende und absteigende Sortierung.
- Dritter Klick setzt die jeweilige Standardsortierung zurück.
- Tastaturbedienbare Sortierbuttons.
- `aria-sort` und Sortierpfeile.
- Deutsche Textsortierung über `Intl.Collator('de-DE', {sensitivity:'base', numeric:true})`.
- Numerische Sortierung für Zeit, Dauer und Zählwerte.
- Kritische beziehungsweise fehlerhafte Zustände werden in den fachlichen Standardsortierungen priorisiert.
- Sortierzustand bleibt beim Aktualisieren erhalten, weil die Tabellen mit den bestehenden `tableStates` erneut gerendert werden.
- Die Sortierung erfolgt ausschließlich innerhalb der jeweiligen fachlichen Gruppe.

Die mobile Prüfung wurde mit Playwright gegen die produktive lokale Oberfläche durchgeführt. Die Tabellen behalten wegen ihrer fachlichen Spaltenbreite einen horizontal scrollbaren Tabellenbereich; die Seite selbst erzeugt keinen horizontalen Header-Überlauf.

## Deutsche Benutzeroberfläche

Sichtbare Status- und Tabellenbegriffe wurden auf Deutsch abgebildet, unter anderem:

- `healthy` → `Fehlerfrei`
- `degraded` → `Gestört`
- `failed` → `Fehlgeschlagen`
- `unknown` → `Unbekannt`
- `unavailable` → `Nicht verfügbar`
- `fresh` → `Aktuell`
- `stale` → `Veraltet`
- `running` → `Läuft`
- `stopped` → `Gestoppt`
- `waiting` → `Wartet`
- `completed` → `Abgeschlossen`

Interne API-, Datenbank-, Collector- und Enumwerte bleiben englisch. Technische Eigennamen wie Systemd-Units, Docker-Container und Job-Keys bleiben unverändert.

Die sprachliche Abnahme ist nicht vollständig abgeschlossen: Im Portal stehen in der vorhandenen statischen Kachelstruktur noch sichtbare Schreib-/Encoding-Restwerte wie `?ffnen` und `Oeffnet`. Diese wurden in dieser Sitzung nicht geändert und sind kein Watcherfehler.

## Warnkachel in der Agent-Solutions-Zentrale

Die Kachel `Worker-Warnungen` steht in der Startseite der Agent-Solutions-Zentrale als erste Kachel und spannt die gesamte erste Grid-Zeile. Darunter folgen die statischen Kacheln in der vorgesehenen Reihenfolge:

1. `Cockpit Carlo`
2. `Projects`
3. `VPS Verwaltung`
4. `KI & Automation`
5. `Hermes Scout`
6. `Hermes VPS`

Die Datenquelle ist ausschließlich die serverseitige Portal-Brücke in `/opt/struktur/portal/app.py`. Sie ruft read-only den Watcher-Endpunkt `/api/v1/alerts/summary` ab und liefert eine validierte Zusammenfassung an den Browser. Das Portal bewertet nicht noch einmal alle Einzeljobs.

Aktueller Kachelstand vom `2026-08-02T17:09:49Z`:

- Gesamtstatus der Warnzusammenfassung: `critical`.
- Watcherstatus innerhalb der Zusammenfassung: `degraded`.
- Aktive Warnfälle: `3`.
- Jobs insgesamt: `22`.
- Fehlerfrei: `19`.
- Gestört: `1`.
- Fehlgeschlagen: `1`.
- Unbekannt: `1`.
- Nicht verfügbare Beobachtung: `1`.
- Ältestes Problem: `Telefon Agent`, Beobachtung nicht verfügbar.

Die Kachel zeigt Warn- beziehungsweise Fehlerfarben abhängig von der verdichteten Zusammenfassung. Ein `degraded`-Watcherstatus bedeutet nicht automatisch, dass der Watcher selbst defekt ist. Im aktuellen Fall ist die Datenbank erreichbar und die Prüfzyklen laufen; die Probleme stammen aus überwachten Quellen und einem fehlenden Docker-Objekt.

Die Kachel verlinkt zur vollständigen Worker-Überwachung unter `https://worker.agentsolutions-mallorca.com`.

## Aktualisierungsfunktionen

### Worker-Überwachung

Die Worker-Oberfläche besitzt einen manuellen Button `Aktualisieren` und einen automatischen Abruf im 15-Sekunden-Intervall.

- Der Browser ruft Status, Jobs, Agenten und Ereignisse gemeinsam ab.
- Der Button wird während eines laufenden Abrufs deaktiviert.
- Parallele manuelle und automatische Abrufe werden über `refreshInFlight` gebündelt.
- `Zuletzt aktualisiert` bezeichnet den letzten erfolgreichen vollständigen Browserabruf.
- `Letzte Watcher-Prüfung` bezeichnet dagegen `status.last_cycle_finished_at`, also den fachlichen Prüfzyklus des Watchers.
- Bei Erfolg erscheint `Aktualisiert` nur nach manuellem Abruf inline in der zweiten Meta-Zeile und wird nach ungefähr 2 Sekunden ausgeblendet.
- Automatische Abrufe erzeugen keine dauerhafte Erfolgsmeldung.
- Bei Abruffehler bleiben bereits geladene Tabellen erhalten; die Fehlermeldung ist temporär.
- Die Sortierzustände der Tabellen bleiben beim Aktualisieren erhalten.

### Agent-Solutions-Zentrale

Die Zentrale besitzt einen globalen Button `Aktualisieren` für die dynamische Warnkachel und ein automatisches 60-Sekunden-Polling.

- Der Abruf erfolgt gegen `/api/worker-alerts` des Portals.
- Das Portal ruft intern `/api/v1/alerts/summary` des Watchers ab.
- `Zuletzt aktualisiert` bezeichnet den letzten erfolgreichen Browserabruf der Portal-Brücke.
- Die Warnkachel enthält zusätzlich `Letzte Prüfung` als relative Darstellung des letzten Watcher-Zyklus.
- Erfolg und Fehler werden temporär unterhalb des Buttons angezeigt; die statische Kachelstruktur wird nicht verändert.
- Ein Bridgefehler blockiert nicht die übrigen Navigationskacheln.
- Vorhandene Daten bleiben im Fehlerfall als letzter Stand sichtbar und werden als veraltet beziehungsweise nicht erreichbar gekennzeichnet.

Die beiden Zeitpunkte sind fachlich verschieden: Browserabruf ist nicht gleich Watcher-Prüfzyklus.

## Tests und technische Nachweise

Die zuletzt ausgeführten isolierten Worker-Watcher-Prüfungen am `2026-08-02` lauteten:

```text
/opt/struktur/hermes-workspace/worker-watcher/.venv/bin/python -m compileall -q src tests
/opt/struktur/hermes-workspace/worker-watcher/.venv/bin/ruff check src tests
/opt/struktur/hermes-workspace/worker-watcher/.venv/bin/mypy src
/opt/struktur/hermes-workspace/worker-watcher/.venv/bin/pytest -q
```

Ergebnis:

- Compileall: erfolgreich.
- Ruff: `All checks passed!`.
- Mypy: `Success: no issues found in 25 source files`.
- Pytest: `34 passed`.

Zusätzliche Browsernachweise:

- Worker-Header und Inhaltsrahmen: 25 Playwright-Checks.
- Aktualisierungsvisualisierung mit stabiler Buttonbreite: 14 Playwright-Checks.
- Desktop-Wide, Desktop, Tablet und Mobil wurden geprüft.
- Der Header-Rahmen wurde gegen die `main`-Begrenzung gemessen.
- Kein horizontaler Seitenüberlauf.
- Manueller Abruf, deaktivierter Button, Ladezustand und temporäre Erfolgsmeldung wurden geprüft.
- Der lokale Health-Endpunkt `/health/live` und die Readiness-Prüfung antworteten mit HTTP 200.
- `/api/v1/alerts/summary` antwortete mit HTTP 200.
- Die Portal-Brücke `/api/worker-alerts` antwortete mit `{"ok":true}`.

Der Auditstand vom `2026-08-01` meldete historisch `29 passed`; der aktuelle Teststand ist mit `34 passed` höher.

## Produktive Aktivierungen

Die Aktivierungen und Prüfungen wurden über mehrere Arbeitsschritte durchgeführt. Verifizierbare aktuelle Zustände:

- `hermes-worker-watcher.service`: aktiv, letzter nachgewiesener Neustart `2026-08-02T17:01:40Z`.
- `portal.service`: aktiv, letzter nachgewiesener Neustart `2026-08-02T16:40:27Z`.
- Worker-Watcher-API: lokal erreichbar und liefert aktuelle Collector- und Alertdaten.
- Warnkachel: produktiv über `portal.service` und die lokale Bridge aktiv.
- Tabellen- und Sortierfunktionen: im Worker-Service enthalten und durch Tests/Browserprüfungen verifiziert.

Historische Auditzeiten vom `2026-08-01`, darunter frühere Aktivierungen ab etwa `20:12 UTC` und ein Neustart um `20:36 UTC`, stammen aus dem damaligen Audit. Für die aktuelle Abnahme ist der zuletzt direkt nachgewiesene Zustand maßgeblich.

## Bekannte Probleme der überwachten Anwendungen

### `project.youtube.e2e`

- Status: `operational_state=stopped`, `health_status=degraded`, `observation_status=fresh`.
- Quelle: `youtube-research-e2e-worker.service` über den Systemd-Collector.
- Nachweis: `LoadState=loaded`, `ActiveState=inactive`, `SubState=dead`, `systemd_Result=success`, Exitcode `0`.
- Zuständiges System: YouTube-E2E-Worker beziehungsweise dessen Betriebsentscheidung.
- Änderung am Watcher erforderlich: Nein.
- Änderung an der überwachten Anwendung beziehungsweise Betriebsplanung: Ja, falls der Worker dauerhaft laufen oder geplant gestartet werden soll.

### `project.youtube.graphiti`

- Status: `operational_state=stopped`, `health_status=failed`, `observation_status=fresh`, Severity `critical`.
- Quelle: `youtube-research-graphiti-worker.service` über den Systemd-Collector.
- Nachweis: `ActiveState=failed`, `SubState=failed`, `systemd_Result=signal`, `ExecMainStatus=15`.
- Ursache laut aktueller Statusquelle: Prozessende durch Signal/Exitcode 15; der Auditkontext weist auf Timeout beziehungsweise Dienstproblem hin.
- Zuständiges System: Graphiti-Worker und dessen Lauf-/Timeout-Konfiguration.
- Änderung am Watcher erforderlich: Nein.
- Änderung an der überwachten Anwendung: Ja, wenn dieser Worker benötigt wird.

### `project.telefon.agent`

- Status: `operational_state=unknown`, `health_status=unknown`, `observation_status=unavailable`, Severity `warning`.
- Quelle: Docker-Collector, Containername `telefon-agent`.
- Nachweis: `container_exists=false`; Docker meldet, dass das Objekt nicht existiert.
- Der Watcher hält den letzten bekannten Jobstatus zurück und kennzeichnet die aktuelle Beobachtung separat als nicht verfügbar.
- Zuständiges System: Telefon-Agent-Deployment beziehungsweise Containerdefinition.
- Änderung am Watcher erforderlich: Nein.
- Änderung an der überwachten Anwendung oder Konfiguration: Ja, falls der Telefon-Agent weiter benötigt wird; alternativ muss die Definition bewusst aus dem Scope entfernt werden.

Diese drei Fälle sind Anwendungs- beziehungsweise Deploymentprobleme. Sie sind nicht als Ausfall des Watchers zu behandeln.

## Noch offene UI-Korrekturen

Der zuletzt ausdrücklich offene Header-Punkt war:

- Titel und Untertitel links.
- Aktualisierungsinformationen und Button rechts.
- identische Inhaltsbreite wie Statuskacheln und Tabellen.
- keine dauerhafte dritte Zeile `Aktualisiert`.
- optionale temporäre Erfolgsmeldung nur inline in der zweiten Zeile.
- kein horizontaler Überlauf.

Dieser Punkt ist inzwischen nicht mehr offen, weil die abschließende Live-Abnahme am `2026-08-02` genau diese Kriterien geprüft hat. Der frühere offene Auftrag wird hier trotzdem als Entwicklungshistorie festgehalten:

- [x] Header-Ausrichtung innerhalb des Inhaltsrahmens live korrigiert und abgenommen.

Weiterhin offen beziehungsweise nicht vollständig sprachlich abgenommen:

- [ ] Portal-Resttexte wie `?ffnen` und `Oeffnet` sprachlich beziehungsweise bezüglich Zeichencodierung bereinigen.
- [ ] Für die Warnkachel eine gesonderte fachliche Abnahme mit echten Statuswechseln durchführen; die aktuelle Kachel-Bridge und der aktive Warnzustand sind technisch nachgewiesen.

Keine dieser offenen UI-Aufgaben ist ein Nachweis für einen Watcherfehler.

## Bewusste Abgrenzungen

- Der Worker-Watcher ist eine Beobachtungs- und Bewertungsinstanz, keine Steuerung produktiver Jobs.
- Monitoring gegenüber Systemd, Docker und Prozessen bleibt read-only.
- Die eigene SQLite-Historie darf geschrieben werden; überwachte Systeme werden nicht verändert.
- Die Agent-Solutions-Zentrale zeigt verdichtete Watcherdaten und bewertet nicht doppelt.
- `degraded` beziehungsweise `critical` in der Warnkachel bedeutet nicht automatisch, dass der Watcher selbst defekt ist.
- Keine Auto-Healing-Funktion.
- Kein künstlicher Remote-Agent, solange kein echter Agent angebunden ist.
- Kein Browser-Spezialcollector ohne nachgewiesenen Browser-Worker.
- Keine fachliche Reparatur von Graphiti, YouTube E2E oder Telefon-Agent in dieser Dokumentation.
- Keine Datenbank-, Konfigurations- oder Dienständerung im Rahmen dieses Dokumentationsauftrags.

## Wichtige Architekturentscheidungen

- Worker-Watcher bleibt zentrale Bewertungsinstanz.
- Agent-Solutions-Zentrale zeigt nur verdichtete Ergebnisse.
- Keine doppelte Alarmbewertung im Hauptpanel.
- Keine Auto-Healing-Funktion.
- Monitoring gegenüber überwachten Systemen bleibt read-only.
- Fehler überwachten Anwendungen werden von Watcherfehlern getrennt.
- Sortierung erfolgt je fachlicher Gruppe.
- Browser-Collector ist nicht erforderlich, solange keine Browser-Worker existieren.
- Remote-Agenten bleiben leer, solange keine Remote-Agenten angebunden sind.
- Interne Statuswerte bleiben englisch; sichtbare Standardtexte werden deutsch dargestellt.
- Zeitstempel des Browserabrufs und des Watcher-Zyklus werden getrennt gezeigt.
- UI-Feedback darf keine dauerhafte zusätzliche Zeile erzeugen.

## Geänderte Dateien

Die beiden Projekte liegen nicht in einem einheitlichen versionierten Projektzustand: `worker-watcher` ist ein ungetracktes Unterverzeichnis des übergeordneten Git-Repositories `/opt/struktur/hermes-workspace`; `/opt/struktur/portal` ist kein Git-Repository. Deshalb werden neben den aktuellen Hashes die Dateirollen und der beobachtete Status angegeben.

### Worker-Watcher

| Datei | Zweck und Änderung | Status |
|---|---|---|
| `/opt/struktur/hermes-workspace/worker-watcher/src/worker_watcher/api.py` | API, Warnzusammenfassung, deutsche UI, Tabellen, Sortierung, Header- und Aktualisierungsdarstellung | produktiv aktiv; SHA-256 `735f24c2183db1987d0b9110bd3eecc3b47f81991d9e90fada548c5187393ce3` |
| `/opt/struktur/hermes-workspace/worker-watcher/src/worker_watcher/alerts.py` | Verdichtung von Warnfällen und Portal-Summary | produktiv aktiv; SHA-256 `604d606837e3863c92e05a7a11f04535a80f378856c6edd8ce02ecf18523d6a2` |
| `/opt/struktur/hermes-workspace/worker-watcher/src/worker_watcher/watcher.py` | globale Statusaggregation und Collector-Isolation | produktiv aktiv; SHA-256 `e485f3fcf6adbdd260070dee3d06a5e43bddb399ba751d09279f96b0fc90ed23` |
| `/opt/struktur/hermes-workspace/worker-watcher/tests/unit/test_alerts.py` | Unit-Tests der Warnzusammenfassung | lokal verifiziert; SHA-256 `b7dcb26b1aa1d6200e06f2b2ad54b570b858d6b93f5a9fae9fbbbacc2b1de9ed` |
| `/opt/struktur/hermes-workspace/worker-watcher/tests/integration/test_api_and_reports.py` | API-, Collector- und UI-Textnachweise | lokal verifiziert; SHA-256 `27b8ac2709aa7ba44099198f96f78f84385f204d8b19fc0067ecec201d691d23` |
| `/opt/struktur/hermes-workspace/worker-watcher/tests/integration/test_isolation.py` | Nachweis, dass Jobprobleme den Watcherstatus beeinflussen | lokal verifiziert; SHA-256 `9cef12e5d42dd0b9e0decf0c28ed6903904a70ea01c278c1d43426c4c65046b3` |
| `/opt/struktur/hermes-workspace/worker-watcher/README.md` | API- und Betriebsdokumentation | Dokumentation; SHA-256 `0d4f79b3f96cbac7e6ec9ae79eda5a41e1b1d4f36278cc4335ebaa7aa954becf` |
| `/opt/struktur/hermes-workspace/worker-watcher/docs/deployment-plan.md` | Produktivaktivierung, Rollback und Dienstbezug | Dokumentation; SHA-256 `3d571dfb93c0c0ba2daf13432659b420544ea4fdb9bd96ed60be8709ffc79ed0` |
| `/opt/struktur/hermes-workspace/worker-watcher/docs/audit-2026-08-01.md` | Historischer Audit und Ausgangswerte | Auditdokument; nicht durch diese Dokumentationsdatei verändert; SHA-256 `b2277aaaa8fb0d168e3a731bb6ebb1f52f945a6b5286edc608e33557c2298cea` |

### Agent-Solutions-Zentrale

| Datei | Zweck und Änderung | Status |
|---|---|---|
| `/opt/struktur/portal/app.py` | Portal, Warnkachel, serverseitige Watcher-Brücke, globale Aktualisierung und Layout | produktiv aktiv über `portal.service`; SHA-256 `361ceed6781bca4b1d73a1ad60508be9520349bd778b018becb79506a97fbd9f` |

Die Projektdateien sind im übergeordneten Workspace beziehungsweise im Portalverzeichnis nicht als sauberer gemeinsamer Git-Diff abnahmefähig. Das übergeordnete Workspace-Repository enthält zahlreiche bereits vorhandene Änderungen und ungetrackte Dateien; diese wurden nicht bereinigt oder überschrieben.

## Sicherungen und Auditdokumente

### Historische Sicherung

Die vom Auftrag verlangte Sicherung existiert:

```text
/tmp/worker-watcher-before-sort-20260801.tar.gz
```

Nachweis zum `2026-08-02`:

- Größe: `595016` Bytes.
- Änderungszeit: `2026-08-01 20:31:16.895228003 +0000`.
- SHA-256: `3034b7fffd71dc3cea956c811bf25964df624e735aebd138b903e02a935169cf`.
- Ablage: nur unter `/tmp`, daher temporär und nicht als dauerhafte Archivierung geeignet.

### Aktuelle UI-Sicherungen

Für die letzten Worker-UI-Korrekturen wurden zusätzlich timestamped Backups unter `/opt/struktur/backups/` angelegt, unter anderem:

- `/opt/struktur/backups/worker-header-refresh-visual-20260802-170115/api.py`
- `/opt/struktur/backups/worker-refresh-inline-confirmation-20260802-165902/api.py`
- `/opt/struktur/backups/worker-header-content-frame-20260802-165738/api.py`

Das maßgebliche Auditdokument ist:

```text
/opt/struktur/hermes-workspace/worker-watcher/docs/audit-2026-08-01.md
```

## Nächste Schritte

### Priorität A

- [x] Header der Worker-Überwachung innerhalb des Inhaltsrahmens ausrichten und live abnehmen.
- [x] Dauerhafte blaue Meldung `Aktualisiert` entfernen; temporäres Inline-Feedback verifizieren.
- [x] Live-Abnahme von Desktop und Mobil durchführen.
- [ ] Graphiti-Worker separat untersuchen.
- [ ] Klären, ob der Telefon-Agent weiterhin benötigt wird oder aus der Watcher-Konfiguration entfernt werden soll.

### Priorität B

- [ ] Bezeichnung und Darstellung der Warnkachel sprachlich abschließend abnehmen.
- [ ] Prüfen, ob die Ereignishistorie bei echten Statuswechseln korrekt erweitert wird.
- [ ] Run-Ebene bei Bedarf für echte lokale One-Shot-Worker produktiv befüllen.
- [ ] Verbleibende Portaltexte wie `?ffnen` und `Oeffnet` korrigieren.

### Priorität C

- [ ] Remote-Agenten nur bei tatsächlichem Bedarf anbinden.
- [ ] Alerts oder weitere Benachrichtigungen erst nach fachlicher Entscheidung bewerten.
- [ ] Auto-Healing weiterhin nicht aktivieren.

## Abnahmestatus

### Nachgewiesen

- Worker-Watcher-Prozess und HTTP-API produktiv erreichbar.
- Datenbank erreichbar, Schema-Version 2 aktiv.
- Drei aktive Collector, zwei deaktivierte Collector.
- 22 Jobs und 22 Instanzen sichtbar.
- Warnzusammenfassung mit drei aktiven Warnfällen verfügbar.
- Portal-Brücke liefert die Watcher-Zusammenfassung.
- Warnkachel und Aktualisierungsfunktionen technisch verifiziert.
- Header-Inhaltsrahmen stimmt mit der Kachel-/Tabellenbreite überein.

### Fachlich degraded

- `project.youtube.e2e` ist geladen, aber inaktiv und fachlich beeinträchtigt.
- `project.youtube.graphiti` ist mit Exitcode 15 fehlgeschlagen.
- `project.telefon.agent` ist als Docker-Quelle nicht verfügbar.
- Der Docker-Collector meldet deshalb einen Collectorfehler; der Watcher läuft trotzdem weiter.

### Offen

- Fachliche Behandlung der drei überwachten Anwendungsprobleme.
- Sprachliche Restkorrekturen im Portal.
- Echte Run-Historie für Quellen ohne Run-ID.
- Entscheidung über Remote-Agenten und spätere Benachrichtigungen.

## Verwandte Obsidian-Notizen

Ein aktiver Obsidian-Vault mit eigener `.obsidian`-Struktur wurde unter `/opt/struktur` nicht gefunden. Der vorhandene Ordner `/opt/struktur/obsidian/vault.DISABLED_legacy_20260521` ist ausdrücklich als deaktivierter Legacy-Vault markiert. Die laufende technische Dokumentationskonvention verweist dagegen auf `/opt/struktur/reports`.

Tatsächlich vorhandene, aber im deaktivierten Legacy-Vault liegende thematische Notizen:

- [[Obsidian-Best-Practices]] — Konventionen für Ordner, Wikilinks und Tags.
- [[KARLO]] — bestehende Kontextnotiz.
- [[OpenClaw_Wissensdokumentation]] — historische Hermes-/OpenClaw-Dokumentation.

Eine aktive thematische Hauptnotiz `Worker-Watcher` oder `Agent Solutions Zentrale Steuerung` wurde nicht gefunden; deshalb wurden keine erfundenen oder leeren Stub-Wikilinks angelegt.

## Nachweise und Quellen

- Worker-Watcher-Projekt: `/opt/struktur/hermes-workspace/worker-watcher`
- Worker-Watcher-Quelloberfläche: `/opt/struktur/hermes-workspace/worker-watcher/src/worker_watcher/api.py`
- Worker-Watcher-Konfiguration: `/opt/struktur/hermes-workspace/worker-watcher/config.yaml`
- Worker-Watcher-Datenbank: `/opt/struktur/hermes-workspace/worker-watcher/data/watcher.sqlite`
- Worker-Watcher-Audit: `/opt/struktur/hermes-workspace/worker-watcher/docs/audit-2026-08-01.md`
- Portal-Projekt: `/opt/struktur/portal`
- Portal-Quelldatei: `/opt/struktur/portal/app.py`
- Dienst: `hermes-worker-watcher.service`
- Dienst: `portal.service`
- Health: `http://127.0.0.1:8088/health`
- Live-Health: `http://127.0.0.1:8088/health/live`
- Readiness: `http://127.0.0.1:8088/health/ready`
- Status: `http://127.0.0.1:8088/api/v1/status`
- Jobs: `http://127.0.0.1:8088/api/v1/jobs`
- Ereignisse: `http://127.0.0.1:8088/api/v1/events`
- Collector: `http://127.0.0.1:8088/api/v1/collectors`
- Collector-Läufe: `http://127.0.0.1:8088/api/v1/collectors/runs`
- Warnzusammenfassung: `http://127.0.0.1:8088/api/v1/alerts/summary`
- Portal-Brücke: `http://127.0.0.1:5052/api/worker-alerts`
- Öffentliche Worker-Oberfläche: `https://worker.agentsolutions-mallorca.com`
- Öffentliche Zentrale: `https://agentsolutions-mallorca.com`
- Sicherung: `/tmp/worker-watcher-before-sort-20260801.tar.gz`